OpenDoc
Development
Framework
ODF support for Cyberdog
ODF Release 1
This package contains CyberStarter (a sample ODFCyberdog part written
using ODF), and ODFCyberLibrary (generic Cyberdog support code for ODF).
Table of Contents
Summary
ODFCyberLibrary is an addition to ODF which makes it easier to support Cyberdog
in your part. It is still evolving (since Cyberdog is only beta), and will
be updated often on the ODF web site at <http://www.devtools.apple.com/odf/>.
You can join the ODF mailing list at <odf-interest@cilabs.org>to discuss this support. There are also Cyberdog-specific mailing lists
available from the Cyberdog web site at <http://cyberdog.apple.com/>.
ODFCyberStarter is a minimal Cyberdog/ODF part. It is similar to the CyberPuppy
example in that all it does is download text and display it (using TextBox).
It implements the recipe for reading text from a CyberStream.
Quick Start
Here is what you need to do to make a Cyberdog part using ODFCyberStarter:
If you haven't installed the ODF Cyberdog support, do so now. This consists
of the ODFCyberLibrary (which goes in your ODFDev folder). You also need
to make sure that you have placed the Cyberdog headers in your CodeWarrior
folder.
Generate Your Part
Use PartMaker to create a part. Open the CyberStarter Template and type
in your own part name and company. Generate the part (save it in your ODFDev
folder so the relative paths are correct).
Build It
Open your part's project (CWPPCDebug) in CodeWarrior and choose Make. The
part will be compiled and linked. Your part is now in the CWPPCDebug folder.
Make an alias to it and put it in your Editors folder. If you have ODFDev
on a different disk than your system folder, then create an Editors folder
at the top level of that disk and put the alias in it.
Configure Cyberdog
ODFCyberStarter displays text, and is bound to the mime type "text/plain".
In order to make Cyberdog use your part instead of the CyberTextViewer,
open the Editor Setup control panel. Click the "Show All" button,
and find the "text/plain" kind. Double-click on that line and
choose your part (CyberTextViewer and possibly ODFCyberStarter will also
be listed). Then close Editor Setup.
Now any time you try to view a text document (not html), Cyberdog will use
your part. If you don't know where any text documents are, you can try this
one: <http://www.meer.net/~mlanett/csdemo.txt>.
ODFCyberStarter (and your derivative part) is a text viewer, but since it
is just a sample, it's not very good. It doesn't show feedback as it loads
the text, and it doesn't scroll. What is illustrated is the minimal work
you need to do to implement Cyberdog support in your part. Here are the
important places in the source code:
Binding.h:
Notice that in addition to the usual kEditor and kKind, we also have defined
kMimeType, in this case "text/plain". If you want to download
a different mime type you should change this. You will also need to change
kind and category to be appropriate. For example, if you want to display
images (such as jpegs), you would choose a kMimeType of "image/jpeg",
and category of kODCategoryPainting. Which kind you would choose is unclear,
because they aren't necessarily registered (CILabs is in charge of this).
In general you should always specify a standard kind; use a propietary one
also if you need to, but be sure to always write out data to a kind which
other parts can read. In the case of an image you might want to write out
a PICT kind.
Part.h and Part.cpp:
CPart inherits from FW_MCyberPart in addition to FW_CPart. In general this
seems to be the simplest approach (since you only ever want to have 1 FW_MCyberPart
instance, and it needs to communicate with the FW_CPart instance, you might
as well make them the same object).
CPart overrides DoSetCyberItem (so it knows when Cyberdog wants it to load
a new item), and DoIdle (to implement the loading).
You won't need to change DoSetCyberItem very much. It erases the content
of the part (setting the text handle to zero-length) and starts the download.
DoIdle needs to be changed depending on your part's data. The outer portion
of the loop stays the same. The inner loop accumulates the text and does
an incremental display.
Some other routines were affected. We had to slightly modify the CPart constructor
and Initialize method. We also override PrivNewEventDispatcher to assist
in dealing with Cyberdog window closing. These changes will be the same
for all Cyberdog-aware parts.
Frame.h and Frame.cpp
We've added a DrawUpdate routine. This is just like Draw, except that it
doesn't erase the screen first. In fact Draw does an erase and then calls
DrawUpdate. We do things like this so that our DoIdle can call DrawUpdate
numerous times, each time displaying more and more text. Also, this part
is a very lame text viewer and uses TextBox, which erases the screen
anyway, causing blinking. Your part should be able to do things more neatly.
Part.r
The binding is the least understood part of OpenDoc, and the hardest to
debug, and the area most likely to be screwed up when making a part Cyberdog-savvy.
The best reason to begin with ODFCyberStarter is because the binding is
set up right. It depends only on the constants in Binding.h, except for
the English-language user strings, so you shouldn't have to mess with it
for a while.
Theory and Design
ODFCyberLibrary contains these classes:
ODF_FW_OCyberPartExtension (SOM) is a subclass of CyberPartExtension,
and overrides all of its public methods. It uses a callback structure (FW_SCyberPartExtensionCallbacks)
so that whenever Cyberdog calls it, it can turn around and call you in C++.
This class will be moved into the ODFLibrary in the future to reduce the
size of your part even further.
FW_MCyberPart (C++) is a C++ class which implements the callbacks
used by ODF_FW_OCyberPartExtension. The end result is that any SOM method
call from Cyberdog (for example, CyberPartExtension::SetCyberItem) will
be turned into a C++ method call. Therefore instead of doing SOM subclassing,
you can do C++ subclassing instead. The easiest thing to do is to multiply
inherit your C++ part class (CPart) from both FW_CPart (or FW_CEmbeddingPart)
and FW_MCyberPart. That way you can implement DoSetCyberItem right in your
part class to load your part's data across the network.
Note that the names of the FW_MCyberPart methods are a little different
than in CyberPartExtension. Most begin with Do (as in DoSetCyberItem), but
two begin with Handle (HandleOpenCyberItem and HandleCyberCommand). The
difference is that if you override a "Do" method you should not
call inherited, but if you override a "Handle" method then you
should call the inherited FW_MCyberPart:: method.
FW_CCyberStream is an "envelope" class for CyberStream.
It ensures that the CyberStream is deleted when you are done using it. It
even calls Abort if you weren't done reading from it. Here is an example
of its use:
FW_CCyberStream cs (myCyberItem->CreateCyberStream(ev));
short status = cs->GetStreamStatus(ev);
while (!(status & FW_kCyberStreamDone)) {
if (status & kCDDataAvailable) {
FW_CCyberBuffer ab (ev, cs);
do_something (ev, ab.GetBuffer(), ab.GetSize());
}
else
::YieldToAnyThread();
status = cs->GetStreamStatus(ev);
}
With FW_CCyberStream you don't need to worry about exceptions, stream errors,
or deleting the stream. It's handled for you.
FW_CCyberBuffer is also an envelope class, this time for a buffer
aquired from a CyberStream. Here is what ordinary code would look like (not
using this helper class):
Ptr buffer;
Size size;
cs->GetBuffer (ev, &buffer, &size);
FW_TRY {
do_something (ev, buffer, size);
}
FW_CATCH_BEGIN
FW_CATCH_EVERYTHING() {
cs->ReleaseBuffer (ev, buffer);
FW_THROW_SAME();
}
FW_CATCH_END
cs->ReleaseBuffer (ev, buffer);
You can simplify all that code to this:
FW_CCyberBuffer ab (ev, cs);
do_something (ev, ab.GetBuffer(), ab.GetSize());
With FW_CCyberBuffer you don't need to worry about exceptions or releasing
the buffer.
ODFCyberStarter is a minimal ODF part provided in PartMaker format,
so you can quickly create the shell for a Cyberdog-"Savvy" ODF
part. It implements the basic reading recipes above with just a text handle,
so you can easily change it depending on your content.
Installation
Before using ODFCyberLibrary you will need to have installed OpenDoc, ODF
and CyberDog.
Cyberdog and ODFCyberLibrary are as of this writing still works in progress.
You should check the ODF web site and Cyberdog web sites for the latest
information. Also, we do not have the Cyberdog SDK on the ODF CD.
You will need to download it from the Cyberdog web site.
Copy ODFCyberLibrary (in the ODF & Cyberdog folder) into your ODFDev
folder.
Optionally copy CyberStarter, or make your own using PartMaker. Again, put
it in your ODFDev folder.
Install the Cyberdog SDK into your CodeWarrior : MacOS Support : Headers
folder (the SDK consists of the Public Includes and Cyberdog.stub).
You will need to add these access paths to your project:
You also need to add these files to your project:
Issues
What if Cyberdog isn't Present?
We haven't yet worked on weak linking against Cyberdog. This will be supported
in a later release on the ODF web site.
What if Threads aren't Present?
Cyberdog requires threads, but once weak linking is supported, you will
be able to run your part without it, which might mean that threads wouldn't
be present either. This will be dealt with along with weak linking.
What about making my part show up in the browser window?
This is on the to-do list. Check the ODF web site (at the top of this document)
for the last version of ODFCyberLibrary and CyberStarter.
What about MrC/Symantec/68K?
Other PPC compilers will be supported with netborne releases. 68K will not,
since Cyberdog does not run on 68K.
Copyright © 1993-1996 Apple Computer, Inc. All rights reserved.
Apple, the Apple Logo, Macintosh, and OpenDoc are trademarks of Apple Computer,
Inc., registered in the United States and other countries.